Hello @pratikshazalte69,

This PR is pretty big! Good work.

Can you provide me a short overview of all the changes? Architecturally as well as functionally.

Thank you

Hello @transistive

Thank you! I’ve prepared a detailed overview of all the changes—both architectural and functionality

Authentication Refactor

• Unified all authentication methods to use BoltConnection.
• Removed dependency on protocol version classes.
• Standardized request-response flow with send()->getResponse().

Connection & Message Factory Improvements

• BoltMessageFactory now initialized with full BoltConnection instead of protocol references.
• Added consistent state tracking for unconsumed results and logging.
• Session::close() now calls discardUnconsumedResults() instead of consumeResults().
• Robust error handling for RESET messages with proper cleanup.
• New discardUnconsumedResults() helper method for explicit result discarding.
• Connection metadata now updated with accurate server agent after authentication.

Changes in the BoltUnmanagedTransaction

• Exception type: Changed from ClientException → TransactionException for clearer, domain-specific errors.
• Error messages: Rephrased to be more concise and context-specific (e.g., "Can't commit a committed transaction.").
• Commit handling: send() → send()->getResponse() to properly wait for the server’s acknowledgment.
• Rollback checks: Removed terminated case; only committed/rolled back states now block rollback.
• Run checks: Added guard clauses to prevent running queries on finished transactions.

Session Refactor: Connection Tracking, Cleanup, and Centralized Retry Handling

• New Session tracks used connections and adds a close() method to discard unconsumed results, preventing leaks.
• Retry logic moved to TransactionHelper for cleaner, centralized handling.
• BoltMessageFactory now takes the full connection instead of just the protocol for better flexibility.
• Improves resource cleanup, maintainability, and robustness.

Introduce TransactionHelper for Centralized Retry and Error Handling

• Extracted transaction retry logic into TransactionHelper.
• Unified retry and rollback handling in one place.
• Centralized transaction retry logic for consistency.

Unify System Update Handling in SummarizedResultFormatter

• Some Neo4j versions return contains-system-updates, others return system-updates.
• Using ($stats['contains-system-updates'] ?? $stats['system-updates'] ?? 0) ensures reliable capture.
• Fallback ?? 0 guarantees numeric value to prevent missing key errors.
• Improves summary accuracy across Neo4j versions.

Query ID (qid) in CypherList

• Added qid to CypherList to uniquely identify the source query.
• Improves traceability, debugging, and result management.

AbstractRunner Handler

• Code changes: Return precise DriverErrorResponse for session/transaction errors, handle TransactionException separately, and simplify result key extraction.
• Improves error reporting, type safety, and maintainability.
• Testkit progress: Backend updated to support refined session and transaction handling.

RetryableNegative and RetryablePositive

• RetryableNegative: Now returns FrontendErrorResponse instead of BackendErrorResponse for proper client reporting.

• RetryablePositive: Updated to actually commit the transaction instead of just returning RetryableDoneResponse.

  • Retrieves transaction from repository, validates it, commits it.
  • Returns DriverErrorResponse if commit fails or BackendErrorResponse if missing.

• Ensures correct retryable behavior and robust error handling.

Decode Transaction Metadata (CypherMap & CypherList)

• SessionBeginTransaction: Added decodeToValue to convert CypherMap/List into PHP objects before passing metadata.
• SessionReadTransaction: Same decoding logic applied for correctness and consistency.
• SessionWriteTransaction: Metadata decoded before execution, ensuring structured data is handled properly.
• Improves compatibility, prevents type mismatches, and ensures Neo4j interprets metadata correctly.

Enhance DriverErrorResponse

• Updated to support both Neo4jException and TransactionException.
• Ensures correct serialization of Neo4j-specific error codes/messages.
• Differentiates between driver-level and transaction-level errors.

Set 24-Hour Timeout for Server Socket

• Added stream_set_timeout($streamSocketServer, 60 * 60 * 24);.
• Ensures socket stays open for long-running operations.
• Improves stability for persistent connections and long-lived test sessions.